\vssub
\subsection{~Optional environment settings}
\vssub

Compilation of the \ws\ NetCDF enabled programs requires the environment variable
{\code WWATCH3\_NETCDF} be set to either {\code NC3} (compile with NetCDF
version 3.x) or {\code NC4} (compile with NetCDF version 4.x).  If the script
variable is set to {\code WWATCH3\_NETCDF = NC3}, then the following
environment variables are required
\begin{clist}
\cit {NETCDF\_LIBDIR} {Path to where the NetCDF-3 libraries are installed.}
\cit {NETCDF\_INCDIR} {Path to where the NetCDF-3 include files are installed.}
\end{clist}
If {\code WWATCH3\_NETCDF = NC4}, then the following environment variable
is required.
\begin{clist}
\cit {NETCDF\_CONFIG} {Path to the NetCDF-4 nc-config utility program.}
\end{clist}
The {\file nf-config} utility program (part of the NetCDF-4 install or 
{\file nc-config} for old versions) is used to determine the appropriate
compile and link flags for the {\code WWATCH3\_NETCDF = NC4} compile.
The NetCDF-4 compile requires NetCDF version 4.1.1 or higher.  Use the command
\command{\code nf-config --version} to check the version of the installed 
Fortran-NetCDF library.  Compiling with the {\code NC4} switch requires
{\code WWATCH3\_NETCDF = NC4} and the NetCDF-4 installation compiled with the
NetCDF-4 API enabled.  Use \command{\code nf-config --has-nc4} to check if the
installed NetCDF has the NetCDF-4 API enabled.

\vspace{\baselineskip} 
\noindent
Compilation of the WAVEWATCH III with PDLIB for Domain Decompstion option
for (Explicit/Implicit) triangular unstructed grids requires the environment
variable {\code METIS\_PATH} be set to the path where {\code Metis} and
{\code ParMetis} are compiled using the same compiler used for WW3.

\vspace{\baselineskip}
\noindent
Two additional remarks need to be made regarding parallel versions of the
model (OpenMP and \mpi\ versions). First, complications may occur when
preparing executables for running in an \mpi\ environment. Such complications
are discussed in Appendix~\ref{app:mpi}. Secondly, the \omp\ code should be
compiled using directives only, i.e., do not use compiler options that
automatically thread the code.



\vssub
\subsection{~Compiling and linking} \label{sec:comp}
\vssub

\vspace{\baselineskip} \noindent 
For the first compilation, the \ws\ environment must be set up using the script
{\file w3\_setup} with the model directory path in argument. Some options are
available to define the compiler options and the switch file located in the
{\dir bin} directory. For instance, \command{w3\_setup /home/user/WW3/model
-c <comp> -s <switch>} the {\code <comp>} keyword can be {\code mpt}, 
{\code intel}, {\code gfortran}, {\code pgi} for optimized compilation options
or could be {\code mpt\_debug}, {\code intel\_debug}, {\code gfortran\_debug},
{\code pgi\_debug} for debugging compilation options. If system-dependant
options are needed, it can be done by modifying the script {\file cmplr.env}. 
Some old comp/link templates from different clusters are still available but 
not recommended. The {\code <switch>} keyword can be the suffix of a provided
switch file or your own one. Running this script will create these three 
scripts/files :

\begin{flist}
\fit{comp}  {Compiler script. This script is based on {\file comp.tmpl} with
	    the provided definition of the compiler and its options.}
\fit{link}  {Linker script. This script is based on {\file link.tmpl} with
	    the provided definition of the linker and its options.}
\fit{switch}{File containing a list of switches as recognized by the
             preprocessor {\file w3adc}. Copied from {\code switch\_<switch>}}.
\end{flist}

\vspace{\baselineskip}

The environment file {\file wwatch3.env} will be created or updated if it 
already exists. The auxiliary FORTRAN programs for code prepocessor will be
compiled using by default the GNU FORTRAN compiler which can be different to
the provided compiler for the \ws\ programs.


\vspace{\baselineskip} \noindent 
The easiest way to compile \ws\ is using the script {\file w3\_automake} to 
automatically detect which programs to compile and to compile it. It will
force pre- and post-processing programs to be compiled as sequential 
implementation and others depending on the switches from openMP, MPI or hybrid
configurations. If the netCDF library is correctly set up, the netCDF dedicated
programs will be also compiled. The same test is done for SCRIPNC, PDLIB, OASIS,
ESMF, TRKNC and TIDE keywords to manage the program compilation in the best way.
For instance, \command{w3\_automake} or for a few programs \command{w3\_automake
ww3\_grid ww3\_shel ww3\_ounf} the compiled programs will all be stored in the 
{\dir exe} directory with a copy of the switch, comp and link files used.

\vspace{\baselineskip} \noindent
In case of troubles during the compilation of a program, the log files will be
stored in a temporary directory which will differs between sequential mode
({\dir tmp\_SEQ}) and distributed mode like MPI ({\dir tmp\_MPI}), OMP 
({\dir tmp\_OMP}) or hybrid ({\dir tmp\_HYB}). There are usually three log files
per program:

\begin{flist}
\fit{\code ww3\_<prog>.l} {full program with only the matching lines
	of codes based on the switches and at the end the compilation command line.}
	\fit{\code ww3\_<prog>.out} {warning messages}
	\fit{\code ww3\_<prog>.err} {error messages}
\end{flist}

To remove all user-created files from the \ws\ framework, the script 
{\file w3\_clean} can be used by only cleaning up the {\dir model} directory
\command{w3\_clean -m} or the full ww3 repository \command{w3\_clean -c}


\vssub
\subsection{~Detailled compilation}
\vssub

Compilation of \ws\ is performed using the script {\file w3\_make} in the
{\dir bin} directory\footnote{~Note that before running {\file w3\_make}
  several user interventions are needed as described in the remainder of this
  section.}.  If this script is used without parameters, all basic programs of
\ws\ are compiled. Optionally, names of programs to be compiled can be given
as part of the compile command. For instance \command{w3\_make ww3\_grid
  ww3\_strt} will compile the grid preprocessor and the initial conditions
program only. {\file w3\_make} uses several of the scripts described in the
previous section. A graphical representation is given in Fig.~\ref{fig:make}.
If necessary, the script {\file w3\_make} uses the scripts {\file
  make\_makefile.sh} to generate a makefile. {\file make\_makefile.sh}
generates a list of modules to be linked, based on the program switches in the
file {\file switch} (see~\para\ref{sec:switches}), and checks all needed
sources for module dependencies. If switches have been changed since the last
call to {\file w3\_make}, {\file w3\_new} is used to `touch' relevant source
code or to delete relevant object files. After the makefile has been
completed, the standard \unix\ make utility is used to compile and link the
programs. Instead of directly using the \fortran\ compiler, the makefile
invokes the preprocessor and compile scripts {\file ad3} and {\file comp}, and
the link script {\file link}. The script {\file ad3} uses the extension of the
file name to determine the necessary action. Files with extension {\file .ftn}
are processed by {\code w3adc}, files with extension {\file .f} or {\file
  .f90} are send to the script {\code comp} directly.  Although a user could
try out several of these scripts interactively, he or she generally needs to
run {\file w3\_make} only.

\input{impl/fig_make} 

\vspace{\baselineskip}

\begin{center}
\rule[1mm]{55mm}{1.0mm} WARNING \rule[1mm]{55mm}{1.0mm} \\
\vspace{\baselineskip}
\parbox{120mm}{The auxiliary scripts {\file w3\_make} etc. use the {\file
  switch}, {\file comp} and {\file link} files from the {\file ./bin}
  directory under the \ws\ home directory, {\it NOT} from the local
  directory.} \\ \vspace{\baselineskip} \rule[1mm]{55mm}{1.0mm} WARNING
  \rule[1mm]{55mm}{1.0mm}
\end{center}


\noindent
After the appropriate changes have been made, or the appropriate example
scripts have been copied in, (parts of) \ws\ can be compiled and linked. When
the program is compiled for the first time, it is suggested to compile program
parts one-by-one to avoid lengthy errors messages, and to set up error
capturing in {\file comp}. A good place to start is compilation of the simple
test code {\F ctest}. First go to the directory {\dir work} and make a link to
the source code of this routine by typing \command{ln3 ctest} This link is
made to facilitate later inclusion of errors to test or set-up error capturing
in the script {\file comp}. The inner workings of the preprocessor {\file
  w3adc} can be seen by typing the command \command{ad3\_test ctest} which
will show how the actual source code is constructed from {\file ctest.ftn},
include files and program switches. Next, the compilation of this subroutine
can be tested by typing \command{ad3 ctest 1} which invokes both the
preprocessor {\file w3adc} and the compile script {\file comp}. The 1 at the
end of this line activates test output. If it is omitted, this command should
result in a single line of output, identifying that the routine is being
processed. If {\file ad3} works as expected, an object file {\file
  obj/ctest.o} is generated. If requested during the initial set up, a source
code and listing file ({\file ctest.f} and {\file ctest.l}) can be found in
the scratch directory. The listing file is also retained if compilation errors
are detected by {\file comp}. At this time, it is prudent to test error
capturing in the script {\file comp} by adding errors and warnings to {\file
  ctest.ftn} in the work directory. The error capturing is discussed in some
detail in the documentation of {\file comp}. After {\file comp} has been
tested, and the errors in {\file ctest.ftn} have been removed, the link to the
work directory and the file {\file obj/ctest.o} can be deleted.

After a single routine has been compiled successfully, the next step is to try
to compile and link an entire program. The grid preprocessor can be compiled
by typing \command{w3\_make ww3\_grid} If the compilation appears successful,
and if the input files have been installed (see above), the grid preprocessor
can be tested by typing \command{ww3\_grid} in the work directory. If the
input files have been installed, a link to the input file {\file
ww3\_grid.inp} will be present in the work directory, and the grid
preprocessor will run and send its output to the screen. Output files of the
grid preprocessor will appear in the work directory. When a program is
compiled for the first time, the operating system might not be able to find
the executable. If this occurs, try to type \command{rehash} or open a new
shell to work from. In this way all separate programs can be compiled and
tested. To clean up all temporarily files (such as listings) and data files of
the test runs, type \command{w3\_clean} Note that {\file w3\_make} only checks
the switch file for changes. If the user changes the compile options in the
compile and link scripts {\file comp} and {\file link}, it is advised to force
the recompilation of the entire program. This can be achieved by typing
\command{w3\_new all {\rm or} w3\_new} before invoking {\file w3\_make}. This
might also be useful if the compilation is unsuccessful for no apparent
reason.


